{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3e2dad39",
   "metadata": {
    "vscode": {
     "languageId": "markdown"
    }
   },
   "source": [
    "# 1. Getting Started\n",
    "\n",
    "Welcome to the GNews Tutorial Notebook!  \n",
    "This section will help you set up the environment and make your first API call using the GNews Python library.\n",
    "\n",
    "### ✅ What You Will Learn\n",
    "- How to install and import GNews\n",
    "- How to initialize the news client\n",
    "- How to fetch your first set of headlines\n",
    "\n",
    "### 📌 Installation\n",
    "Run the below command in your terminal or notebook cell to install:\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "076317ec",
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install gnews\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56fd91da",
   "metadata": {},
   "source": [
    "###  Import and Initialize GNews\n",
    "\n",
    "Once installed, import the library and create a simple `GNews()` object.  \n",
    "This object will be our main tool for fetching news.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "36afc550",
   "metadata": {},
   "outputs": [],
   "source": [
    "from gnews import GNews\n",
    "google_news = GNews()\n",
    "google_news\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "71db973b",
   "metadata": {},
   "source": [
    "### Fetch Your First News Results\n",
    "\n",
    "Now let's fetch news by a keyword — for example, `\"Sports\"`.\n",
    "Below, you will get a list of articles, each containing:\n",
    "\n",
    "- `title`\n",
    "- `description`\n",
    "- `published date`\n",
    "- `url`\n",
    "- `publisher`\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9b351766",
   "metadata": {},
   "outputs": [],
   "source": [
    "trending_news = google_news.get_top_news()\n",
    "trending_news[:3]\n",
    " # Displays first 3 news articles about Sports"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b5a23bcb",
   "metadata": {},
   "source": [
    "## 2. Filtering News by Various Criteria\n",
    "\n",
    "GNews allows powerful filtering options so you can control **{what type of news you fetch*}**.  \n",
    "In this section, we will explore:\n",
    "\n",
    "- Filtering by `language`\n",
    "- Filtering by `country`\n",
    "- Limiting results using `max_results`\n",
    "- Fetching by `topic`\n",
    "- Fetching by date range\n",
    "\n",
    "You can try yourdelf with various features\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f72f3f61",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Filter by Language and Country\n",
    "india_news = GNews(language='en', country='IN',max_results=10)\n",
    "india_news=india_news.get_news('Politics')\n",
    "india_news[:3]\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "567b1283",
   "metadata": {},
   "source": [
    "### 📰 Filter News by Topic\n",
    "GNews supports a variety of topics such as:\n",
    "\n",
    "`WORLD, NATION, BUSINESS, TECHNOLOGY, ENTERTAINMENT, SPORTS, SCIENCE, HEALTH, POLITICS`\n",
    "You can change the topics and check it yourself "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "da6ab06d",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Available topics: {You can try out any of these topics by replacing 'Sports' in the code above}\n",
    "\n",
    "# ` WORLD, NATION, BUSINESS, TECHNOLOGY, ENTERTAINMENT, SPORTS, SCIENCE, HEALTH, POLITICS, CELEBRITIES, TV, MUSIC, MOVIES, THEATER, SOCCER, CYCLING, MOTOR SPORTS, TENNIS,\n",
    "#  COMBAT SPORTS, BASKETBALL, BASEBALL, FOOTBALL, SPORTS BETTING,#  WATER SPORTS, HOCKEY, GOLF, #CRICKET, RUGBY, ECONOMY, PERSONAL FINANCE, FINANCE, DIGITAL CURRENCIES, MOBILE,\n",
    "#  ENERGY, GAMING, INTERNET SECURITY, GADGETS, VIRTUAL REALITY, ROBOTICS, NUTRITION, PUBLIC HEALTH, MENTAL HEALTH, MEDICINE, SPACE, WILDLIFE, ENVIRONMENT, NEUROSCIENCE, PHYSICS,\n",
    "#  GEOLOGY, PALEONTOLOGY, SOCIAL SCIENCES, EDUCATION, JOBS, ONLINE EDUCATION, HIGHER EDUCATION, VEHICLES, ARTS-DESIGN, BEAUTY, FOOD, TRAVEL, SHOPPING, HOME, OUTDOORS, FASHION.\n",
    "\n",
    "world_news = google_news.get_news_by_topic('WORLD')\n",
    "world_news[:3]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb3543f3",
   "metadata": {},
   "source": [
    "### 📰 Filter News by Country\n",
    "GNews supports a variety of Countries such as:\n",
    "\n",
    "`Australia, Botswana, Canada , Ethiopia, Ghana, India` - You can change the country upon your intrest \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "18fcbb36",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Available Countries: \n",
    "\n",
    "# {'Australia': 'AU', 'Botswana': 'BW', 'Canada ': 'CA', 'Ethiopia': 'ET', 'Ghana': 'GH', 'India ': 'IN',\n",
    "#  'Indonesia': 'ID', 'Ireland': 'IE', 'Israel ': 'IL', 'Kenya': 'KE', 'Latvia': 'LV', 'Malaysia': 'MY', 'Namibia': 'NA',\n",
    "#  'New Zealand': 'NZ', 'Nigeria': 'NG', 'Pakistan': 'PK', 'Philippines': 'PH', 'Singapore': 'SG', 'South Africa': 'ZA',\n",
    "#  'Tanzania': 'TZ', 'Uganda': 'UG', 'United Kingdom': 'GB', 'United States': 'US', 'Zimbabwe': 'ZW',\n",
    "#  'Czech Republic': 'CZ', 'Germany': 'DE', 'Austria': 'AT', 'Switzerland': 'CH', 'Argentina': 'AR', 'Chile': 'CL',\n",
    "#  'Colombia': 'CO', 'Cuba': 'CU', 'Mexico': 'MX', 'Peru': 'PE', 'Venezuela': 'VE', 'Belgium ': 'BE', 'France': 'FR',\n",
    "#  'Morocco': 'MA', 'Senegal': 'SN', 'Italy': 'IT', 'Lithuania': 'LT', 'Hungary': 'HU', 'Netherlands': 'NL',\n",
    "#  'Norway': 'NO', 'Poland': 'PL', 'Brazil': 'BR', 'Portugal': 'PT', 'Romania': 'RO', 'Slovakia': 'SK', 'Slovenia': 'SI',\n",
    "#  'Sweden': 'SE', 'Vietnam': 'VN', 'Turkey': 'TR', 'Greece': 'GR', 'Bulgaria': 'BG', 'Russia': 'RU', 'Ukraine ': 'UA',\n",
    "#  'Serbia': 'RS', 'United Arab Emirates': 'AE', 'Saudi Arabia': 'SA', 'Lebanon': 'LB', 'Egypt': 'EG',\n",
    "#  'Bangladesh': 'BD', 'Thailand': 'TH', 'China': 'CN', 'Taiwan': 'TW', 'Hong Kong': 'HK', 'Japan': 'JP',\n",
    "#  'Republic of Korea': 'KR'}\n",
    "\n",
    "country_news = google_news.get_news_by_country('IN')\n",
    "country_news[:3]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4a62be9f",
   "metadata": {},
   "source": [
    "### 📰 Choose your Language\n",
    "GNews supports a variety of languages such as:\n",
    "\n",
    "`Arabic,hindi,,English,Japanese,chinese,spanish,french,german,` - You can change the language upon your intrest "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "496c4e26",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Available Languages:  \n",
    "#   \n",
    "# {'Arabic': 'ar', 'German': 'de', 'English': 'en', 'Spanish': 'es', 'French': 'fr', 'Hindi': 'hi', 'Italian': 'it',\n",
    "#  'Japanese': 'ja', 'Korean': 'ko', 'Dutch': 'nl', 'Polish': 'pl', 'Portuguese': 'pt', 'Russian': 'ru', 'Turkish': 'tr', 'Chinese': 'zh'}\n",
    "\n",
    "language_news = google_news.get_news_by_language('de')\n",
    "language_news[:3]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f28b1d67",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Control the Number of Results\n",
    "google_news.max_results = 3\n",
    "few_news = google_news.get_news('AI')\n",
    "few_news"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "39e8717f",
   "metadata": {},
   "outputs": [],
   "source": [
    "#Filter by Date Range - > Format: `(YYYY, MM, DD)`\n",
    "google_news = GNews(\n",
    "    start_date=(2025, 1, 1),\n",
    "    end_date=(2025, 3, 1),\n",
    "    max_results=5\n",
    ")\n",
    "\n",
    "date_filtered_news = google_news.get_news('Economy')\n",
    "date_filtered_news[:3]\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2a09607",
   "metadata": {},
   "source": [
    "### ✅ Summary\n",
    "\n",
    "| Filter Type | Parameter | Example |\n",
    "|------------|-----------|---------|\n",
    "| Language | `language` | `'en'` |\n",
    "| Country | `country` | `'IN'` |\n",
    "| Max Results | `max_results` | `10` |\n",
    "| Topic | `get_news_by_topic('TECHNOLOGY')` | |\n",
    "| Date Range | `start_date`, `end_date` | `(2024, 1, 1)` |\n",
    "\n",
    "You've now learned how to precisely control your news results! 🎉\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e9c9ebef",
   "metadata": {},
   "source": [
    "### 3. Exporting News Data\n",
    "\n",
    "Once you fetch news using GNews, you can export it for further analysis, reporting, or storage.  \n",
    "In this section, we will export data into:\n",
    "\n",
    "- JSON format\n",
    "- CSV format\n",
    "- Pandas DataFrame (for data analysis workflows)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3602c1f7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# 📌 Export as JSON\n",
    "import json\n",
    "sample_news = google_news.get_news('Climate Change')\n",
    "json_output = json.dumps(sample_news, indent=4)\n",
    "json_output #--> Displays news articles in JSON format\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "66981707",
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install pandas"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e64023bc",
   "metadata": {},
   "outputs": [],
   "source": [
    "# 📌 Export as CSV\n",
    "import pandas as pd\n",
    "sample_news = google_news.get_news('Health')\n",
    "df = pd.DataFrame(sample_news)\n",
    "df.to_csv('health_news.csv', index=False) # --> health_news.csv file is created with the news articles"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "81bd9ff1",
   "metadata": {},
   "outputs": [],
   "source": [
    "# 📌 Convert to DataFrame\n",
    "import pandas as pd\n",
    "sample_news = google_news.get_news('Environment')\n",
    "df = pd.DataFrame(sample_news)\n",
    "df.head()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ad6ce95",
   "metadata": {},
   "source": [
    "### ✅ Summary\n",
    "\n",
    "You now know how to export GNews results in three ways:\n",
    "\n",
    "| Format | Use Case |\n",
    "|---------|----------|\n",
    "| JSON | Store raw structured data |\n",
    "| CSV | Share or analyze using spreadsheet tools |\n",
    "| Pandas DataFrame | Ideal for data analysis and ML |\n",
    "\n",
    "In the next section, we will use this DataFrame for **{real analysis (sentiment analysis example)}**.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bcae7ebc",
   "metadata": {},
   "source": [
    "## 4. Advanced Features & Best Practices\n",
    "\n",
    "In this section, we cover:\n",
    "- Filtering by time periods\n",
    "- Excluding specific websites\n",
    "- Fetching news by geo-location\n",
    "- Combining multiple filters for precise results\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "89588b20",
   "metadata": {},
   "outputs": [],
   "source": [
    "from gnews import GNews\n",
    "\n",
    "# Initialize with advanced parameters\n",
    "google_news = GNews(\n",
    "    language='en',\n",
    "    country='US',\n",
    "    max_results=10,\n",
    "    period='7d',  # last 7 days\n",
    "    exclude_websites=['yahoo.com','cnn.com'],\n",
    "    include_websites=['bbc.com','techcrunch.com'],\n",
    "    proxy='https://your_proxy_address:port'  # Replace with your proxy if needed\n",
    ")\n",
    "\n",
    "# Fetch news with multiple filters\n",
    "tech_news = google_news.get_news('Artificial Intelligence')\n",
    "df_tech = pd.DataFrame(tech_news)\n",
    "df_tech.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5c1d8267",
   "metadata": {},
   "outputs": [],
   "source": [
    "# You can  change the feature of an existing object\n",
    "\n",
    "google_news.period = '7d'  # News from last 7 days\n",
    "google_news.max_results = 10  # number of responses across a keyword\n",
    "google_news.country = 'United States'  # News from a specific country \n",
    "google_news.language = 'english'  # News in a specific language\n",
    "google_news.exclude_websites = ['zerodha.com', 'bbc.com']  # Exclude news from specific website i.e Yahoo.com and CNN.com\n",
    "google_news.start_date = (2020, 1, 1) # Search from 1st Jan 2020\n",
    "google_news.end_date = (2020, 3, 1) # Search until 1st March 2020"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4af113d8",
   "metadata": {},
   "source": [
    "### Fetching News from Specific Sites\n",
    "\n",
    "Sometimes you only want news from trusted sources (e.g., TechCrunch, BBC, or CNN) \n",
    "to ensure the quality and reliability of your dataset.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6e8875f0",
   "metadata": {},
   "outputs": [],
   "source": [
    "from gnews import GNews\n",
    "import pandas as pd\n",
    "\n",
    "\n",
    "news = GNews(language='en', country='US', max_results=10)\n",
    "\n",
    "# Fetch news only from a specific site\n",
    "techcrunch_news = news.get_news_by_site('techcrunch.com')\n",
    "techcrunch_news"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "70b484c7",
   "metadata": {},
   "source": [
    "### Collecting News for Multiple Keywords\n",
    "\n",
    "Sometimes, research or analysis requires gathering news on **several topics** at once.  \n",
    "Instead of fetching each keyword separately, we can loop through a list of keywords and **combine results into a single dataset**.  \n",
    "\n",
    "**Key Benefits:**\n",
    "- Create a **multi-topic dataset** for analysis.\n",
    "- Automatically **tag articles by keyword** for classification or NLP tasks.\n",
    "- Prepare data quickly for **AI/ML projects** or research papers.\n",
    "\n",
    "**Example Use Case:**  \n",
    "Collecting news about `Artificial Intelligence`, `Climate Change`, and `Cryptocurrency` in one go, and labeling each article with its corresponding keyword.\n",
    "\n",
    "### You can Explore More Topics \n",
    "\n",
    "- Politics & Government  \n",
    "- Travel & Tourism  \n",
    "- Food & Recipes  \n",
    "- Mental Health & Wellness  \n",
    "- Fashion & Lifestyle  \n",
    "- Renewable Energy & Sustainability\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7d1321d3",
   "metadata": {},
   "outputs": [],
   "source": [
    "keywords = ['Travel & Tourism', 'Climate Change', 'Cryptocurrency']\n",
    "all_news = []\n",
    "\n",
    "for kw in keywords:\n",
    "    news = google_news.get_news(kw)\n",
    "    for article in news:\n",
    "        article['keyword'] = kw  # tag with keyword\n",
    "    all_news.extend(news)\n",
    "\n",
    "df_keywords = pd.DataFrame(all_news)\n",
    "df_keywords.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21a6b8b7",
   "metadata": {},
   "source": [
    "### 5. Sentiment Analysis on a Single News Article\n",
    "\n",
    "Sometimes you want to quickly check the sentiment of **{ one news headline or description }**.  \n",
    "We'll demonstrate this using VADER sentiment analysis on a single article.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b9a3dc06",
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install vaderSentiment matplotlib seaborn\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b5ed2c58",
   "metadata": {},
   "outputs": [],
   "source": [
    "from vaderSentiment.vaderSentiment import SentimentIntensityAnalyzer\n",
    "\n",
    "analyzer = SentimentIntensityAnalyzer()\n",
    "sample_article = df.iloc[0]  # first row\n",
    "title = sample_article['title']\n",
    "description = sample_article['description']\n",
    "\n",
    "# Get sentiment scores\n",
    "sentiment_scores = analyzer.polarity_scores(description)\n",
    "\n",
    "# Classify sentiment\n",
    "if sentiment_scores['compound'] > 0.05:\n",
    "    sentiment_label = 'Positive'\n",
    "elif sentiment_scores['compound'] < -0.05:\n",
    "    sentiment_label = 'Negative'\n",
    "else:\n",
    "    sentiment_label = 'Neutral'\n",
    "\n",
    "print(f\"Title: {title}\\n\")\n",
    "print(f\"Description: {description}\\n\")\n",
    "print(f\"Sentiment Score: {sentiment_scores}\")\n",
    "print(f\"Sentiment Label: {sentiment_label}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ea0bf59",
   "metadata": {},
   "source": [
    "### ✅ Output Explanation\n",
    "\n",
    "- `compound` score is the main sentiment indicator:\n",
    "  -  . > 0.05 → Positive\n",
    "  - < -0.05 → Negative\n",
    "  - Otherwise → Neutral\n",
    "- This small snippet shows how to analyze **{any single news article}** quickly.\n",
    "- Perfect for testing or debugging before analyzing larger datasets.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6120ca4",
   "metadata": {},
   "source": [
    "### 📊 Data Visualization — Understanding Sentiment with Charts\n",
    "\n",
    "Now that we have classified the sentiment of a sample news article, let's **visualize the sentiment scores** to understand the emotional tone more clearly.\n",
    "\n",
    "Data visualization helps us answer questions like:\n",
    "\n",
    "- *How positive or negative is this news article?*\n",
    "- *Is the sentiment mostly neutral or strongly emotional?*\n",
    "- *Which sentiment dominates the description?*\n",
    "\n",
    "We will create a **bar chart** to display the `positive`, `negative`, and `neutral` sentiment intensities.  \n",
    "This makes our sentiment analysis more insightful and easier to interpret at a glance.\n",
    "\n",
    "Next, you can optionally extend this by plotting sentiment distribution for multiple articles using a **pie chart** or **histogram**.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1eda038d",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# Extract sentiment scores \n",
    "scores = {k: v for k, v in sentiment_scores.items() if k != 'compound'}\n",
    "\n",
    "plt.figure(figsize=(6,4))\n",
    "plt.bar(scores.keys(), scores.values())\n",
    "plt.title(\"Sentiment Score Breakdown\")\n",
    "plt.xlabel(\"Sentiment Category\")\n",
    "plt.ylabel(\"Score\")\n",
    "plt.show()\n"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
